home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 February: Tool Chest / Apple Developer CD Series Tool Chest February 1996 (Apple Computer)(1996).iso / Sample Code / AOCE Sample Code / PowerTalk Access Modules / Sample SMSAM / SampleSMSAM Source / CoreGateway / HalfGateway.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-07-28  |  6.8 KB  |  160 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        HalfGateway.h
  3.  
  4.     Copyright:    © 1991-1994 by Apple Computer, Inc.
  5.                 All rights reserved.
  6.  
  7.     Part of the AOCE Sample SMSAM Package.  Consult the license
  8.     which came with this software for your specific legal rights.
  9.  
  10. */
  11.  
  12.  
  13.  
  14. /***********************************|****************************************/
  15.  
  16. #ifndef __HALFGATEWAY__
  17. #define __HALFGATEWAY__
  18.  
  19. #ifndef __BLJSTANDARDINCLUDES__
  20. #include "BLJStandardIncludes.h"
  21. #endif
  22.  
  23. #ifndef    __DIRECTOBJECT__
  24. #include "DirectObject.h"
  25. #endif
  26.  
  27. /***********************************|****************************************/
  28.  
  29. class TLetter;
  30. class TMailGateway;
  31. class ATupleKey;
  32. class ADataItem;
  33.  
  34. /***********************************|****************************************/
  35.  
  36. class THalfGateway : public TDirectObject
  37. {
  38. public:    virtual                 ~THalfGateway();
  39.  
  40.         virtual ostream&             operator >> ( ostream& ) const;
  41.  
  42.  
  43.         TMailGateway*                 GetGateway () const { return fMailGateway; };
  44.  
  45. //
  46. //    HALF-GATEWAY SETUP METHODS
  47. //
  48. //    After all of the half gateways have been created and the MailGateway object is
  49. //    itself setup, it will call each HalfGateway's Setup() method.  The halfgateway
  50. //    should do what is necessary to get itself set-up and configured, and then return.
  51. //    The gateway should not initiate any time-consuming activities during set-up.
  52. //
  53.         virtual Boolean             Setup ( TMailGateway& mailGateway, short vRefNum, long dirID, const char* gatewayName );
  54.  
  55.  
  56. //    HALF-GATEWAY RECOVERY METHODS
  57. //
  58. //         Crash recovery will be performed after Setup and before the Run() method is
  59. //    called.  The MailGateway will first call the BeginRecoveryPhase() method, after which
  60. //    the halfgateway may begin crash recovery operations.  During this phase, the
  61. //    halfgateway should use the ResendLetter() and RereceiveLetter() methods.  The
  62. //    halfgateway will probably create a new thread in BeginRecoveryPhase() and then
  63. //    immediately return, but the half-gateway may choose to perform all operations and
  64. //    just return.
  65. //        Any letter which was previously sent via the SendLetter() method, and
  66. //    which still has at least one responsible recipient for which no recipient status
  67. //    has been returned, should be resent during startup.  Letters for which no information
  68. //    about any recipient's status has been returned should be sent with the standard
  69. //    SendLetter() method.
  70. //        The halfgateway must be prepared to accept letters via the ReceiveLetter() and
  71. //    RereceiveLetter() methods during the setup phase.  Letters which should be resent
  72. //    will arrive via ReceiveLetter().  Letters which do not need to be resent, but which
  73. //    are resent because they have not been fully acknowledged, will come in through
  74. //    RereceiveLetter().  It is permissible to treat letters which arrive via RereceiveLetter
  75. //    as if they are being received for the first time, with the caveat that doing so may
  76. //    cause some recipients to receive multiple copies of each letter.
  77. //        After the gateway has completed all recovery duties, the method IsRecoveryDone()
  78. //    should begin to return true.  The IsRecoveryDone() method may be called before
  79. //    BeginRecoveryPhase() is called.  Once all halfgateways have finished their crash recovery,
  80. //    the MailGateway will call the FinishRecoveryPhase() method for each half gateway.
  81. //
  82.         virtual Boolean             BeginRecoveryPhase(void) = 0;
  83.         virtual Boolean             IsRecoveryDone(void) = 0;
  84.         virtual Boolean             FinishRecoveryPhase(void) = 0;
  85.     
  86.         virtual Boolean             ResendLetter (TLetter* letter);
  87.         virtual Boolean             RereceiveLetter (TLetter* letter) = 0;
  88.  
  89. //
  90. //    HALF-GATEWAY OPERATION METHODS
  91. //
  92. //        Once the half-gateway has been setup and the crash recovery phase has begun,
  93. //    the mailgateway will call the Run() method for each half gateway.  This method MUST
  94. //    create at least one new thread (which will perform the functions of the half gateway)
  95. //    and then return.  If the gateway has some problem, such that it can not run, Run() should
  96. //    return false; otherwise Run() should return true.
  97.         virtual Boolean             Run (void) = 0;
  98.  
  99.     //    To send a letter from this halfgateway to a destination half-gateway, use the
  100.     //    SendLetter() method.  If an error occurs, return false; otherwise return true.
  101.         virtual Boolean             SendLetter (TLetter* letter);
  102.  
  103.     //    This method will be called by the MailGateway with a letter that this halfgateway
  104.     //    needs to handle.  If an error occurs, return false; otherwise return true.
  105.         virtual Boolean             ReceiveLetter (TLetter* letter) = 0;
  106.  
  107.     //        Eventually, the gateway will need to be shut down.  The MailGateway will call each
  108.     //    halfgateway's PrepareToShutDown() method.  This method should do what is possible to
  109.     //    shut the gateway down.  The inHowManySeconds is supplied as a request for what speed
  110.     //    should be used; it does not require a commitment to be ready to shut down in that time.
  111.     //    Typically, shutting down would involve handling any letters already in the receive pipeline,
  112.     //    but would not result in generating new letters to the destination halfgateway.
  113.     //    During this time, the IsHalfGatewayShuttingDown() function should return true.  When this
  114.     //    halfgateway is prepared to shut down, IsHalfGatewayReadyToShutDown() should return true.
  115.     //    The method CancelHalfGatewayShutdown() may be called by the MailGateway after
  116.     //    PrepareToShutdown(), and would indicate that the MailGateway is no longer shutting down
  117.     //    and so all operations can continue.  Finally, after all of the halfgateways have
  118.     //    reached the prepared-to-shutdown-phase (as indicated by each returning true to
  119.     //    IsHalfGatewayReadyToShutDown() method), the MailGateway will call the ShutDown() method
  120.     //    for each one.  After this is done, starting up the gateway again would require that
  121.     //    the sequence from BeginRecoveryPhase() onward be called again.
  122.         virtual Boolean                PrepareToShutDown(long inHowManySeconds);
  123.         virtual Boolean                IsHalfGatewayShuttingDown(void);
  124.         virtual Boolean                IsHalfGatewayReadyToShutDown(void);
  125.         virtual Boolean                CancelHalfGatewayShutdown (void);
  126.         virtual Boolean                ShutDown(void);
  127.  
  128.         virtual Boolean                GetStatusStr ( Str255& statusStr ) const;
  129.  
  130.  
  131.         virtual Boolean                HandleMonitoringEvent ( const ADataItem& event );
  132.  
  133.     //
  134.     //    CONFIGURATION / SETUP METHODS
  135.     //    =============================
  136.     //
  137.         virtual Boolean             GetConfigItem(const ATupleKey& key, ADataItem& );
  138.         virtual Boolean             SetConfigItem(const ATupleKey& key, const ADataItem& );
  139.         virtual Boolean             DeleteConfigItem(const ATupleKey& key);
  140.         virtual Boolean             GetNthConfigKey(unsigned long index, ATupleKey& key);
  141.  
  142.     //
  143.     //    STATUS REPORTING / ERROR REPORTING OPTIONS
  144.     //    ==========================================
  145.     //
  146.         virtual Boolean             GetStatusItem(const ATupleKey& key, ADataItem&);
  147.         virtual Boolean             SetStatusItem(const ATupleKey& key, const ADataItem& );
  148.     
  149. protected:                            THalfGateway ();
  150.                                     THalfGateway ( TMailGateway& );
  151.                 
  152.                                     TMailGateway* fMailGateway;
  153. };
  154.  
  155. /***********************************|****************************************/
  156.  
  157. #endif    // __HALFGATEWAY__
  158.  
  159.  
  160.